
<html><HEAD>
<LINK REL=STYLESHEET HREF="default.css" TYPE="text/css">
<TITLE>
Context information </TITLE>
</HEAD>
<BODY>

<!-- Header -->
<p class="ancestor" align="right"><A HREF="apptechp127.htm">Previous</A>&nbsp;&nbsp;<A HREF="apptechp129.htm" >Next</A>
<!-- End Header -->
<A NAME="CFHDGCJH"></A><h1>Context information </h1>
<A NAME="TI3900"></A><p>The PowerBuilder context feature allows applications to access
certain host (non-PowerBuilder) services. This is a PowerBuilder
implementation of functionality similar to the COM QueryInterface.
PowerBuilder provides access to the following host services:<A NAME="TI3901"></A>
<ul>
<li class=fi><A HREF="apptechp128.htm#CFHCHFBI">Context information service</A> </li>
<li class=ds><A HREF="apptechp128.htm#CFHEAJDC">Context keyword service</A></li>
<li class=ds><A HREF="apptechp128.htm#CACIDHAI">CORBACurrent service</A></li>
<li class=ds><A HREF="apptechp128.htm#CHEBAIHD">Error logging service</A></li>
<li class=ds><A HREF="apptechp128.htm#CFHDAICJ">Internet service</A></li>
<li class=ds><A HREF="apptechp128.htm#CHEBGHHD">Secure Sockets Layer service</A></li>
<li class=ds><A HREF="apptechp128.htm#CHECJBJH">Transaction server service</A>
</li>
</ul>
</p>
<A NAME="TI3902"></A><p>PowerBuilder creates service objects appropriate for the current
execution context (native PowerBuilder or transaction server). This
allows your application to take full advantage of the execution
environment. </p>
<A NAME="TI3903"></A><p>The context feature uses seven PowerBuilder service objects: ContextInformation,
ContextKeyword, CORBACurrent, ErrorLogging, Inet, SSLServiceProvider,
and TransactionServer; it also uses the InternetResult object. (The
context feature is sometimes called the Context object, but it is <i>not</i> a
PowerBuilder system object.)</p>
<A NAME="TI3904"></A><p>For more information about these objects,
see <i>Objects and Controls</i>
 or the PowerBuilder
Browser.</p>
<A NAME="TI3905"></A><h4>Enabling a service</h4>
<A NAME="TI3906"></A><p>Before you use a service, you instantiate it by calling the <b>GetContextService</b> function.
When you call this function, PowerBuilder returns a reference to
the instantiated service. Use this reference in dot notation when
calling the service's functions.</p>
<A NAME="TI3907"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To enable a service:</p>
<ol><li class=fi><p>Establish an instance variable of the appropriate
type:</p><p><p><PRE> ContextInformation icxinfo_base</PRE><PRE> ContextKeyword     icxk_base</PRE><PRE> CORBACurrent       corbcurr_base</PRE><PRE> ErrorLogging       erl_base</PRE><PRE> Inet               iinet_base</PRE><PRE> SSLServiceProvider sslsp_base</PRE><PRE> TransactionServer  ts_base</PRE></p></li>
<li class=ds><p>Instantiate the instance variable by calling the <b>GetContextService</b> function:</p><p><p><PRE> this.GetContextService("ContextInformation",  &amp;<br>   icxinfo_base)</PRE><PRE> this.GetContextService("ContextKeyword", icxk_base)<br>// Use Keyword instead of ContextKeyword on EAServer</PRE><PRE> this.GetContextService("Keyword", icxk_base) </PRE><PRE> this.GetContextService("CORBACurrent", &amp;</PRE><PRE>    corbcurr_base)</PRE><PRE> this.GetContextService("ErrorLogging", erl_base)</PRE><PRE> this.GetContextService("Internet", iinet_base)</PRE><PRE> this.GetContextService("SSLServiceProvider", &amp;</PRE><PRE>    sslsp_base)</PRE><PRE> this.GetContextService("TransactionServer",ts_base)</PRE></p></li></ol>
<br><A NAME="TI3908"></A><h4>Using a CREATE statement</h4>
<A NAME="TI3909"></A><p>You can instantiate a service object with a PowerScript <b>CREATE</b> statement. However,
this always creates an object for the default context (native PowerBuilder
execution environment), regardless of where the application is running.</p>
<A NAME="CFHCHFBI"></A><h2>Context information service</h2>
<A NAME="TI3910"></A><p>You use the context information service to obtain information
about an application's execution context. The service provides
current version information, as well as whether the application
is running in the PowerBuilder execution environment. </p>
<A NAME="TI3911"></A><h4>Accessing context information</h4>
<A NAME="TI3912"></A><p>Using the context information service, you can access the
information in <A HREF="apptechp128.htm#CACBJBID">Table 21-4</A>.</p>
<A NAME="CACBJBID"></A><table cellspacing=0 cellpadding=6 border=1 frame="void" rules="all"><caption>Table 21-4: Context information</caption>
<tr><th  rowspan="1"  ><A NAME="TI3913"></A>Item</th>
<th  rowspan="1"  ><A NAME="TI3914"></A>Use this function</th>
<th  rowspan="1"  ><A NAME="TI3915"></A>Comment</th>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI3916"></A>Full context name</td>
<td  rowspan="1"  ><A NAME="TI3917"></A><b>GetName</b> </td>
<td  rowspan="1"  ><A NAME="TI3918"></A>Value returned depends on the context:<A NAME="TI3919"></A>
<ul>
<li class=fi>Default: PowerBuilder Runtime
</li>
</ul>
</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI3920"></A>Abbreviated context name </td>
<td  rowspan="1"  ><A NAME="TI3921"></A><b>GetShortName</b> </td>
<td  rowspan="1"  ><A NAME="TI3922"></A>Value returned depends on the context:<A NAME="TI3923"></A>
<ul>
<li class=fi>Default: PBRUN
</li>
</ul>
</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI3924"></A>Company name</td>
<td  rowspan="1"  ><A NAME="TI3925"></A><b>GetCompanyName</b> </td>
<td  rowspan="1"  ><A NAME="TI3926"></A>Returns Sybase, Inc.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI3927"></A>Version</td>
<td  rowspan="1"  ><A NAME="TI3928"></A><b>GetVersionName</b> </td>
<td  rowspan="1"  ><A NAME="TI3929"></A>Returns the full version number (for example,
11.5.0.1)</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI3930"></A>Major version</td>
<td  rowspan="1"  ><A NAME="TI3931"></A><b>GetMajorVersion</b> </td>
<td  rowspan="1"  ><A NAME="TI3932"></A>Returns the major version number (for example,
11.5)</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI3933"></A>Minor version</td>
<td  rowspan="1"  ><A NAME="TI3934"></A><b>GetMinorVersion</b> </td>
<td  rowspan="1"  ><A NAME="TI3935"></A>Returns the minor version number (for example,
0)</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI3936"></A>Fix version</td>
<td  rowspan="1"  ><A NAME="TI3937"></A><b>GetFixesVersion</b> </td>
<td  rowspan="1"  ><A NAME="TI3938"></A>Returns the fix version number (for example,
1)</td>
</tr>
</table>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Using the ClassName function for context information</span> <A NAME="TI3939"></A>You can also use the <b>ClassName</b> function
to determine the context of the object.</p>
<A NAME="TI3940"></A><p>You can use this information to verify that the context supports
the current version. For example, if your application requires features
or fixes from Version 11.5.0.1, you can use the context information
service to check the version in the current execution context.</p>
<A NAME="TI3941"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To access context information:</p>
<ol><li class=fi><p>Declare an instance or global variable
of type ContextInformation:</p><p><p><PRE> ContextInformation icxinfo_base</PRE></p></li>
<li class=ds><p>Create the context information service by calling
the GetContextService function:</p><p><p><PRE> this.GetContextService("ContextInformation", &amp;</PRE><PRE>    icxinfo_base)</PRE></p></li>
<li class=ds><p>Call context information service functions as
necessary. </p><p>This example calls the <b>GetShortName</b> function
to determine the current context and the <b>GetVersionName</b> function
to determine the current version:<p><PRE> String  ls_name</PRE><PRE> String  ls_version</PRE><PRE> Constant String ls_currver = "11.5.01"</PRE><PRE> icxinfo_base.GetShortName(ls_name)</PRE><PRE> IF ls_name &lt;&gt; "PBRun" THEN</PRE><PRE>    cb_close.visible = FALSE</PRE><PRE> END IF</PRE><PRE> icxinfo_base.GetVersionName(ls_version)</PRE><PRE> IF ls_version &lt;&gt; ls_currver THEN</PRE><PRE>    MessageBox("Error",  &amp;</PRE><PRE>       "Must be at Version " + ls_currver)</PRE><PRE> END IF</PRE></p></li></ol>
<br><A NAME="CFHEAJDC"></A><h2>Context keyword service</h2>
<A NAME="TI3942"></A><p>Use the context keyword service to access environment information
for the current context. In the default environment, this service
returns host workstation environment variables. When running within <ABBR title = "e a server" >EAServer</ABBR>, you can use the keyword
service to get a specific component property value (on all <ABBR title = "e a server" >EAServer </ABBR> platforms except AIX,
you must use Keyword as the string parameter in the <b>GetContextService</b> function).</p>
<A NAME="TI3943"></A><p>For information about using the context keyword service in <ABBR title = "e a server" >EAServer</ABBR>, see <A HREF="apptechp142.htm#CCJCIGFE">"Accessing component properties"</A>.</p>
<A NAME="TI3944"></A><h4>Accessing environment variables</h4>
<A NAME="TI3945"></A><p>When running in the PowerBuilder execution environment (the
default context), you use this service to return environment variables. </p>
<A NAME="TI3946"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To access environment variables:</p>
<ol><li class=fi><p>Declare an instance or global variable
of type ContextKeyword. Also declare an unbounded array of type
String to contain returned values:</p><p><p><PRE> ContextKeyword  icxk_base</PRE><PRE> String   is_values[]</PRE></p></li>
<li class=ds><p>Create the context information service by calling
the <b>GetContextService</b> function:</p><p><p><PRE> this.GetContextService("Keyword", icxk_base)</PRE></p></li>
<li class=ds><p>Call the <b>GetContextKeywords</b> function
to access the environment variable you want. This example calls
the <b>GetContextKeywords</b> function to determine
the current application <i>Path</i>:</p><p><p><PRE> icxk_base.GetContextKeywords("Path", is_values)</PRE></p></li>
<li class=ds><p>Extract values from the returned array as necessary.
When accessing environment variables, the array should always have
a single element:</p><p><p><PRE> MessageBox("Path", "Path is: " + is_values[1])</PRE></p></li></ol>
<br><A NAME="CACIDHAI"></A><h2>CORBACurrent service</h2>
<A NAME="TI3947"></A><p>Client applications and <ABBR title = "e a server" >EAServer</ABBR> components
marked as OTS style can create, control, and obtain information
about <ABBR title = "e a server" >EAServer</ABBR> transactions using
functions of the CORBACurrent context service object. The CORBACurrent
object provides most of the methods defined for the CORBA Current
interface. </p>
<A NAME="TI3948"></A><p>For more information, see <A HREF="apptechp153.htm#BABJIAFE">"Client- and component-demarcated
transactions"</A>.</p>
<A NAME="CHEBAIHD"></A><h2>Error logging service</h2>
<A NAME="TI3949"></A><p>To record errors generated by PowerBuilder objects running
in a transaction server to a log file, create an instance of the
ErrorLogging service object and invoke its log method. For example:</p>
<A NAME="TI3950"></A><p><p><PRE> ErrorLogging erlinfo_base</PRE><PRE> this.GetContextService("ErrorLogging",  &amp;</PRE><PRE>    erlinfo_base)</PRE><PRE> erlinfo_base.log("Write this string to log")</PRE></p>
<A NAME="TI3951"></A><p>The errors are recorded in the <ABBR title = "e a server" >EAServer</ABBR> log
if the component is running in <ABBR title = "e a server" >EAServer</ABBR>,
and in the Windows system application log if the component is running
in COM+.</p>
<A NAME="CFHDAICJ"></A><h2>Internet service</h2>
<A NAME="TI3952"></A><p>Use the Internet service to:<A NAME="TI3953"></A>
<ul>
<li class=fi>Display
a Web page in the default browser (<b>HyperLinkToURL</b> function, which
starts the default browser with the specified URL)</li>
<li class=ds>Access the HTML for a specified page (<b>GetURL</b> function,
which performs an HTTP <b>Get</b>)</li>
<li class=ds>Send data to a CGI, ISAPI, or NSAPI program (<b>PostURL</b> function,
which performs an HTTP <b>Post</b>)
</li>
</ul>
</p>
<A NAME="TI3954"></A><h4>Hyperlinking to a URL</h4>
<A NAME="TI3955"></A><p>You call the Internet service's <b>HyperLinkToURL</b> function
to start the default browser with a specified URL.</p>
<A NAME="TI3956"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To hyperlink to a URL:</p>
<ol><li class=fi><p>Declare an instance or global variable
of type Inet:</p><p><p><PRE> Inet  iinet_base</PRE></p></li>
<li class=ds><p>Create the Internet service by calling the <b>GetContextService</b> function:</p><p><p><PRE> THIS.GetContextService("Inet", iinet_base)</PRE></p></li>
<li class=ds><p>Call the <b>HyperLinkToURL</b> function,
passing the URL of the page to display when the browser starts:</p><p><p><PRE> iinet_base.HyperlinkToURL  &amp;</PRE><PRE>    ("http://www.sybase.com")</PRE></p></li></ol>
<br><A NAME="TI3957"></A><h4>Getting a URL</h4>
<A NAME="TI3958"></A><p>You call the Internet service's <b>GetURL</b> function
to perform an HTTP <b>Get</b>, returning raw HTML for
a specified URL. This function returns the raw HTML using the InternetResult
object.</p>
<A NAME="TI3959"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To perform an HTTP Get:</p>
<ol><li class=fi><p>Declare an instance or global variable
of type Inet. Also declare an instance or global variable using
the descendent InternetResult object as the datatype (<b>n_ir_msgbox</b> in
this example):</p><p><p><PRE> Inet  iinet_base</PRE><PRE> n_ir_msgbox  iir_msgbox</PRE></p></li>
<li class=ds><p>Create the Internet service by calling the <b>GetContextService</b> function:</p><p><p><PRE> THIS.GetContextService("Internet", iinet_base)</PRE></p></li>
<li class=ds><p>Create an instance of the descendent InternetResult
object:</p><p><p><PRE> iir_msgbox = CREATE n_ir_msgbox</PRE></p></li>
<li class=ds><p>Call the <b>GetURL</b> function, passing
the URL of the page to be returned and a reference to the instance
of the descendent InternetResult object:</p><p><p><PRE> iinet_base.GetURL  &amp;</PRE><PRE>    ("http://www.sybase.com", iir_msgbox)</PRE></p><p>When the <b>GetURL</b> function completes, it
calls the <b>InternetData</b> function defined in the
descendent InternetResult object, passing the HTML for the specified
URL.</p></li></ol>
<br><A NAME="TI3960"></A><h4>Posting to a URL</h4>
<A NAME="TI3961"></A><p>You call the Internet service's <b>PostURL</b> function
to perform an HTTP <b>Post</b>, sending data to a CGI,
ISAPI, or NSAPI program. This function returns the raw HTML using
the InternetResult object.</p>
<A NAME="TI3962"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To perform an HTTP Post:</p>
<ol><li class=fi><p>Declare an instance or global variable
of type Inet. Also declare an instance or global variable using
the descendent InternetResult object as the datatype (<b>n_ir_msgbox</b> in
this example):</p><p><p><PRE> Inet  iinet_base</PRE><PRE> n_ir_msgbox  iir_msgbox</PRE></p></li>
<li class=ds><p>Create the Internet service by calling the <b>GetContextService</b> function:</p><p><p><PRE> THIS.GetContextService("Internet", iinet_base)</PRE></p></li>
<li class=ds><p>Create an instance of the descendent InternetResult
object:</p><p><p><PRE> iir_msgbox = CREATE n_ir_msgbox</PRE></p></li>
<li class=ds><p>Establish the arguments to the <b>PostURL</b> function:</p><p><p><PRE> Blob    lblb_args</PRE><PRE> String  ls_headers</PRE><PRE> String  ls_url</PRE><PRE> Long    ll_length</PRE><PRE> ls_url = "http://coltrane.sybase.com/"</PRE><PRE> ls_url += "cgi-bin/pbcgi80.exe/"</PRE><PRE> ls_url += "myapp/n_cst_html/f_test?"</PRE><PRE> lblb_args = Blob("")</PRE><PRE> ll_length = Len(lblb_args)</PRE><PRE> ls_headers = "Content-Length: "  &amp;<br>   + String(ll_length) + "~n~n"</PRE></p></li>
<li class=ds><p>Call the <b>PostURL</b> function,
passing the URL of the routine to be executed, the arguments, the
header, an optional server port specification, and a reference to
the instance of the descendent InternetResult object:</p><p><p><PRE> iinet_base.PostURL  &amp;<br>   (ls_url, lblb_args, ls_headers, 8080, iir_msgbox)</PRE></p><p>When the <b>PostURL</b> function completes, it
calls the <b>InternetData</b> function defined in the
descendent InternetResult object, passing the HTML returned by the
specified routine.</p></li></ol>
<br><A NAME="TI3963"></A><h4>Using the InternetResult object</h4>
<A NAME="TI3964"></A><p>The <b>GetURL</b> and <b>PostURL</b> functions
both receive data in an InternetResult object. This object acts
as a buffer, receiving and caching the asynchronous data as it is
returned by means of the Internet. When all data is received, the InternetResult
object calls its <b>InternetData</b> function, which
you override to process the data as appropriate.</p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Implement in descendants of InternetResult</span> <A NAME="TI3965"></A>You implement this feature by creating standard class user
objects of type InternetResult. In each of these descendent user
objects, define an <b>InternetData</b> function to process
the passed HTML as appropriate.</p>
<A NAME="TI3966"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To implement a descendent InternetResult object:</p>
<ol><li class=fi><p>Create a standard class user object of
type InternetResult.</p></li>
<li class=ds><p>Declare a new user object function as follows:<A NAME="TI3967"></A>
<ul>
<li class=fi><b>Name</b>   InternetData</li>
<li class=ds><b>Access</b>   Public</li>
<li class=ds><b>Returns</b>   Integer</li>
<li class=ds><b>Argument name</b>   Data, passed by value</li>
<li class=ds><b>Argument datatype</b>   Blob
</li>
</ul>

                        </p></li>
<li class=ds><p>Add code to the <b>InternetData</b> function
that processes the returned HTML as appropriate. This example simply
displays the HTML in a MessageBox:</p><p><p><PRE> MessageBox("Returned HTML", &amp;<br>   String(data, EncodingANSI!))</PRE><PRE> Return 1</PRE></p></li></ol>
<br><A NAME="CHEBGHHD"></A><h2>Secure Sockets Layer service</h2>
<A NAME="TI3968"></A><p>PowerBuilder allows you to establish Secure Sockets Layer
(SSL) connections to <ABBR title = "e a server" >EAServer</ABBR>.
The SSL protocol allows connections to be secured using public-key
encryption and authentication algorithms that are based on digital certificates.
SSL is a "wrapper" protocol: packets for another protocol are secured
by embedding them inside SSL packets. For example, HTTPS is HTTP secured
by embedding each HTTP packet within an SSL packet. Likewise, IIOPS
is IIOP embedded within SSL.</p>
<A NAME="TI3969"></A><p>You use an instance of the SSLServiceProvider object to establish
the connection from the client to the server. For more information,
see the <i>PowerScript Reference</i>
 and <A HREF="apptechp157.htm#CHDGJFAA">Chapter 25, "Using SSL in PowerBuilder clients."</A></p>
<A NAME="CHECJBJH"></A><h2>Transaction server service</h2>
<A NAME="TI3970"></A><p>Use the transaction server service to access information about
the context of an object running in a transaction server such as <ABBR title = "e a server" >EAServer</ABBR>. You can use the TransactionServer
object to influence transaction behavior programmatically, and to
access the methods of another component on the transaction server.</p>
<A NAME="TI3971"></A><p>For more information, see <A HREF="apptechp133.htm#CBBBFDAD">Chapter 23, "Building an <ABBR title = "e a server" >EAServer</ABBR> Component."</A></p>

